IRIX Base Documentation 1998 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / Xm / XmQTnavigator.z / XmQTnavigator

Wrap

Text File | 1998-10-30 | 21KB | 397 lines

XXXXmmmmQQQQTTTTnnnnaaaavvvviiiiggggaaaattttoooorrrr((((3333XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV XXXXmmmmQQQQTTTTnnnnaaaavvvviiiiggggaaaattttoooorrrr((((3333XXXX)))) NNNNAAAAMMMMEEEE _X_m_Q_T_n_a_v_i_g_a_t_o_r - A widget holding this trait can act as a navigator SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS #include <Xm/NavigatorT.h> typedef struct { int version; XmNavigatorMoveCBProc changeMoveCB; XmNavigatorSetValueProc setValue; XmNavigatorGetValueProc getValue; } XmNavigatorTraitRec, *XmNavigatorTrait; vvvvooooiiiidddd ((((****XXXXmmmmNNNNaaaavvvviiiiggggaaaattttoooorrrrMMMMoooovvvveeeeCCCCBBBBPPPPrrrroooocccc))))( WWWWiiiiddddggggeeeetttt, XXXXttttCCCCaaaallllllllbbbbaaaacccckkkkPPPPrrrroooocccc, XXXXttttPPPPooooiiiinnnntttteeeerrrr, BBBBoooooooolllleeeeaaaannnn, vvvvooooiiiidddd ((((****XXXXmmmmNNNNaaaavvvviiiiggggaaaattttoooorrrrSSSSeeeettttVVVVaaaalllluuuueeeePPPPrrrroooocccc))))( WWWWiiiiddddggggeeeetttt, XXXXmmmmNNNNaaaavvvviiiiggggaaaattttoooorrrrDDDDaaaattttaaaa, BBBBoooooooolllleeeeaaaannnn, vvvvooooiiiidddd ((((****XXXXmmmmNNNNaaaavvvviiiiggggaaaattttoooorrrrGGGGeeeettttVVVVaaaalllluuuueeeePPPPrrrroooocccc))))( WWWWiiiiddddggggeeeetttt, XXXXmmmmNNNNaaaavvvviiiiggggaaaattttoooorrrrDDDDaaaattttaaaa); VVVVEEEERRRRSSSSIIIIOOOONNNN This page documents Motif 2.1. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN A child widget holding the _X_m_Q_T_n_a_v_i_g_a_t_o_r trait can act as a navigator widget. A user can manipulate a navigator widget in order to make different parts of a scrollable widget visible. In the standard Motif widget set, the XXXXmmmmSSSSccccrrrroooollllllllBBBBaaaarrrr and XXXXmmmmSSSSppppiiiinnnnBBBBooooxxxxwidgets hold the _X_m_Q_T_n_a_v_i_g_a_t_o_r trait. In the Exm demonstration widget set, the EEEExxxxmmmmPPPPaaaannnnnnnneeeerrrr widget holds this trait. Widgets holding the _X_m_Q_T_n_a_v_i_g_a_t_o_r trait can cooperate with widgets holding the _X_m_Q_T_s_c_r_o_l_l_F_r_a_m_e trait. Two of the trait methods, sssseeeettttVVVVaaaalllluuuueeee and ggggeeeettttVVVVaaaalllluuuueeee, require an XXXXmmmmNNNNaaaavvvviiiiggggaaaattttoooorrrrDDDDaaaattttaaaa structure, which has the following definition: typedef struct { Mask valueMask; Mask dimMask; XmTwoDIntRec *value; XmTwoDIntRec *minimum; Page 1 (printed 10/24/98) XXXXmmmmQQQQTTTTnnnnaaaavvvviiiiggggaaaattttoooorrrr((((3333XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV XXXXmmmmQQQQTTTTnnnnaaaavvvviiiiggggaaaattttoooorrrr((((3333XXXX)))) XmTwoDIntRec *maximum; XmTwoDIntRec *slider_size; XmTwoDIntRec *increment; XmTwoDIntRec *page_increment; } XmNavigatorDataRec, *XmNavigatorData; where _X_m_T_w_o_D_I_n_t_R_e_c is a 2-field structure defined as follows: typedef struct { int x; int y; } XmTwoDIntRec, *XmTwoDInt; Following is a detailed description of the fields of the XXXXmmmmNNNNaaaavvvviiiiggggaaaattttoooorrrrDDDDaaaattttaaaa structure: _v_a_l_u_e_M_a_s_k Holds a bit vector mask. Each bit in the bit vector mask represents a different field in the XXXXmmmmNNNNaaaavvvviiiiggggaaaattttoooorrrrDDDDaaaattttaaaa structure. If a bit is set, then the data for that field is valid. If that bit is not set, then the data within that field is ignored. Motif provides the following constants, each representing one bit of the bit mask. The caller can add any combination of the following constants in order to form the appropriate _v_a_l_u_e_M_a_s_k value: NNNNaaaavvvvDDDDiiiimmmmMMMMaaaasssskkkk Validates the _d_i_m_M_a_s_k field. NNNNaaaavvvvVVVVaaaalllluuuueeee Validates the _v_a_l_u_e field. NNNNaaaavvvvMMMMiiiinnnniiiimmmmuuuummmm Validates the _m_i_n_i_m_u_m field. NNNNaaaavvvvMMMMaaaaxxxxiiiimmmmuuuummmm Validates the _m_a_x_i_m_u_m field. NNNNaaaavvvvSSSSlllliiiiddddeeeerrrrSSSSiiiizzzzeeee Validates the _s_l_i_d_e_r__s_i_z_e field. NNNNaaaavvvvIIIInnnnccccrrrreeeemmmmeeeennnntttt Validates the _i_n_c_r_e_m_e_n_t field. NNNNaaaavvvvPPPPaaaaggggeeeeIIIInnnnccccrrrreeeemmmmeeeennnntttt Validates the _p_a_g_e__i_n_c_r_e_m_e_n_t field. NNNNaaaavvvvAAAAllllllllVVVVaaaalllliiiidddd Validates all fields. _d_i_m_M_a_s_k Holds a bit vector mask. Each bit in the bit Page 2 (printed 10/24/98) XXXXmmmmQQQQTTTTnnnnaaaavvvviiiiggggaaaattttoooorrrr((((3333XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV XXXXmmmmQQQQTTTTnnnnaaaavvvviiiiggggaaaattttoooorrrr((((3333XXXX)))) vector mask represents a different dimension. Currently, the only two supported dimensions are _x and _y. Therefore, 1 bit of this mask represents the _x dimension and another bit represents the _y dimension. Motif provides the following constants, each representing 1 bit of the bit mask. The caller may add any combination of the following constants in order to form the appropriate _d_i_m_M_a_s_k value: NNNNaaaavvvviiiiggggDDDDiiiimmmmeeeennnnssssiiiioooonnnnXXXX Validates the _x dimension. NNNNaaaavvvviiiiggggDDDDiiiimmmmeeeennnnssssiiiioooonnnnYYYY Validates the _y dimension. The value of the _d_i_m_M_a_s_k field affects the interpretation of the _v_a_l_u_e, _m_i_n_i_m_u_m, _m_a_x_i_m_u_m, _s_l_i_d_e_r__s_i_z_e, _i_n_c_r_e_m_e_n_t, and _p_a_g_e__i_n_c_r_e_m_e_n_t fields. The value of _d_i_m_M_a_s_kaffects these other fields even if NNNNaaaavvvvDDDDiiiimmmmMMMMaaaasssskkkk is not set. In fact, the only time that NNNNaaaavvvvDDDDiiiimmmmMMMMaaaasssskkkk has influence is when the caller is trying to change or read the value of _d_i_m_M_a_s_k. _v_a_l_u_e Holds a TTTTwwwwooooDDDDIIIInnnnttttRRRReeeecccc structure containing two values: one is the value of the navigator widget in the _x dimension, and the other is the value in the _y dimension. For example, suppose the _v_a_l_u_e in the _x dimension is 50, the _m_i_n_i_m_u_m is 10, and the _m_a_x_i_m_u_m is 90. In this case, the navigator widget will have a horizontal position halfway between the left and right sides of the widget. _m_i_n_i_m_u_m Holds a TTTTwwwwooooDDDDIIIInnnnttttRRRReeeecccc structure containing two values: one is the minimum value of the navigator widget in the _x dimension and the other is the minimum value in the _y dimension. _m_a_x_i_m_u_m Holds a TTTTwwwwooooDDDDIIIInnnnttttRRRReeeecccc structure containing two values: one is the maximum value of the navigator widget in the _x dimension and the other is the maximum value in the _y dimension. _s_l_i_d_e_r__s_i_z_e Holds a TTTTwwwwooooDDDDIIIInnnnttttRRRReeeecccc structure containing two values: one is the slider size of the navigator widget in the _x dimension and the other is the slider size in the _y dimension. The _s_l_i_d_e_r__s_i_z_e value is not an absolute value; for example, it is not a size in pixels. The actual size of the slider is based on the ratio of the _s_l_i_d_e_r__s_i_z_e to Page 3 (printed 10/24/98) XXXXmmmmQQQQTTTTnnnnaaaavvvviiiiggggaaaattttoooorrrr((((3333XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV XXXXmmmmQQQQTTTTnnnnaaaavvvviiiiggggaaaattttoooorrrr((((3333XXXX)))) the difference between the _m_i_n_i_m_u_m and _m_a_x_i_m_u_m. For example, suppose the _s_l_i_d_e_r__s_i_z_e in the _x dimension is 20, the _m_i_n_i_m_u_m is 10, and the _m_a_x_i_m_u_m is 90. In this case, the difference between the _m_i_n_i_m_u_m and the _m_a_x_i_m_u_m is 80. Therefore, the slider will occupy 20/80 (or 25%) of the allocated widget space in the _x dimension. _i_n_c_r_e_m_e_n_t Holds a TTTTwwwwooooDDDDIIIInnnnttttRRRReeeecccc structure containing two values: one is the increment size of the navigator widget in the _x dimension and the other is the increment size in the _y dimension. The increment size is the amount by which the _v_a_l_u_eincreases or decreases when the user takes an action that moves the slider by one increment. _p_a_g_e__i_n_c_r_e_m_e_n_t Holds a TTTTwwwwooooDDDDIIIInnnnttttRRRReeeecccc structure containing two values: one is the page increment size of the navigator widget in the _x dimension and the other is the page increment size in the _y dimension. The page increment size is the amount by which the _v_a_l_u_e increases or decreases when the user takes an action that moves the slider by one page increment. TTTThhhheeee cccchhhhaaaannnnggggeeeeMMMMoooovvvveeeeCCCCBBBB TTTTrrrraaaaiiiitttt MMMMeeeetttthhhhoooodddd vvvvooooiiiidddd cccchhhhaaaannnnggggeeeeMMMMoooovvvveeeeCCCCBBBB( WWWWiiiiddddggggeeeetttt nnnnaaaavvvviiiiggggaaaattttoooorrrrWWWWiiiiddddggggeeeetttt, XXXXttttCCCCaaaallllllllbbbbaaaacccckkkkPPPPrrrroooocccc mmmmoooovvvveeeeCCCCBBBB, XXXXttttPPPPooooiiiinnnntttteeeerrrr cccclllloooossssuuuurrrreeee, BBBBoooooooolllleeeeaaaannnn sssseeeettttUUUUnnnnsssseeeetttt); The cccchhhhaaaannnnggggeeeeMMMMoooovvvveeeeCCCCBBBB trait method is responsible for adding or removing the _m_o_v_e_C_B callback from the list of callbacks. A child widget holding the _X_m_Q_T_n_a_v_i_g_a_t_o_r trait should provide a resource that holds the name of the move callback procedure. This callback will be activated whenever a user moves an indicator in the _n_a_v_i_g_a_t_o_r_W_i_d_g_e_t. Following is a sample implementation of this trait method. In this implementation, the _E_x_m_N_m_o_v_e_C_a_l_l_b_a_c_k resource holds the name of the move callback procedure. NavigChangeMoveCB( Widget navigatorWidget, XtCallbackProc moveCB, XtPointer closure, Boolean setunset) { if (setunset) XtAddCallback (navigatorWidget, ExmNmoveCallback, moveCB, closure); Page 4 (printed 10/24/98) XXXXmmmmQQQQTTTTnnnnaaaavvvviiiiggggaaaattttoooorrrr((((3333XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV XXXXmmmmQQQQTTTTnnnnaaaavvvviiiiggggaaaattttoooorrrr((((3333XXXX)))) else XtRemoveCallback (navigatorWidget, ExmNmoveCallback, moveCB, closure); } _n_a_v_i_g_a_t_o_r_W_i_d_g_e_t Specifies the child widget that is to have its list of callbacks modified. _m_o_v_e_C_B Specifies the callback procedure that is to be added or removed from the list of callbacks. _c_l_o_s_u_r_e Specifies additional data to be passed to the callback. _s_e_t_U_n_s_e_t Specifies a BBBBoooooooolllleeeeaaaannnn value. If this value is _T_r_u_e, the sssseeeettttVVVVaaaalllluuuueeeetrait method adds _m_o_v_e_C_B to the list of callbacks. If this value is _F_a_l_s_e, the _m_o_v_e_C_B is removed from the list of callbacks. TTTThhhheeee sssseeeettttVVVVaaaalllluuuueeee TTTTrrrraaaaiiiitttt MMMMeeeetttthhhhoooodddd vvvvooooiiiidddd sssseeeettttVVVVaaaalllluuuueeee( WWWWiiiiddddggggeeeetttt nnnnaaaavvvviiiiggggaaaattttoooorrrrWWWWiiiiddddggggeeeetttt, XXXXmmmmNNNNaaaavvvviiiiggggaaaattttoooorrrrDDDDaaaattttaaaa nnnnaaaavvvviiiiggggaaaattttoooorrrrDDDDaaaattttaaaa, BBBBoooooooolllleeeeaaaannnn nnnnoooottttiiiiffffyyyy); The sssseeeettttVVVVaaaalllluuuueeee trait method allows the caller to pass new navigator data to the _n_a_v_i_g_a_t_o_r_W_i_d_g_e_t. _n_a_v_i_g_a_t_o_r_W_i_d_g_e_t Specifies the navigator widget that provides this method. _n_a_v_i_g_a_t_o_r_D_a_t_a Specifies an XXXXmmmmNNNNaaaavvvviiiiggggaaaattttoooorrrrDDDDaaaattttaaaa structure whose fields describe the characteristics of the navigator widget. _n_o_t_i_f_y Specifies a BBBBoooooooolllleeeeaaaannnn value. If _T_r_u_e, the caller wants sssseeeettttVVVVaaaalllluuuueeee to activate the move callback procedure whenever there is a change in the _v_a_l_u_e field of the _n_a_v_i_g_a_t_o_r_D_a_t_a structure. TTTThhhheeee ggggeeeettttVVVVaaaalllluuuueeee TTTTrrrraaaaiiiitttt MMMMeeeetttthhhhoooodddd vvvvooooiiiidddd ggggeeeettttVVVVaaaalllluuuueeee( WWWWiiiiddddggggeeeetttt nnnnaaaavvvviiiiggggaaaattttoooorrrrWWWWiiiiddddggggeeeetttt, XXXXmmmmNNNNaaaavvvviiiiggggaaaattttoooorrrrDDDDaaaattttaaaa nnnnaaaavvvviiiiggggaaaattttoooorrrrDDDDaaaattttaaaa); The ggggeeeettttVVVVaaaalllluuuueeee trait method returns the current _n_a_v_i_g_a_t_o_r_D_a_t_aheld by the _n_a_v_i_g_a_t_o_r_W_i_d_g_e_t. Not all of the fields in the returned _n_a_v_i_g_a_t_o_r_D_a_t_a will hold valid data. The caller of ggggeeeettttVVVVaaaalllluuuueeeemust analyze the returned _v_a_l_u_e_M_a_s_k and _d_i_m_M_a_s_k fields to determine which of the other fields Page 5 (printed 10/24/98) XXXXmmmmQQQQTTTTnnnnaaaavvvviiiiggggaaaattttoooorrrr((((3333XXXX)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV XXXXmmmmQQQQTTTTnnnnaaaavvvviiiiggggaaaattttoooorrrr((((3333XXXX)))) hold valid data. _n_a_v_i_g_a_t_o_r_W_i_d_g_e_t Specifies the navigator widget that provides this method. _n_a_v_i_g_a_t_o_r_D_a_t_a Specifies an XXXXmmmmNNNNaaaavvvviiiiggggaaaattttoooorrrrDDDDaaaattttaaaa structure whose fields describe the characteristics of the navigator widget. RRRREEEELLLLAAAATTTTEEEEDDDD XXXXmmmmQQQQTTTTssssccccrrrroooollllllllFFFFrrrraaaammmmeeee(3), XXXXmmmmSSSSccccrrrroooollllllllBBBBaaaarrrr(3), XXXXmmmmSSSSppppiiiinnnnBBBBooooxxxx(3), and EEEExxxxmmmmPPPPaaaannnnnnnneeeerrrr(3). Page 6 (printed 10/24/98)